home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 2 / AACD 2.iso / AACD / Programming / perlman / man / perlstyle.txt < prev    next >
Encoding:
Text File  |  1999-09-09  |  8.9 KB  |  228 lines
  1. NAME
  2.        perlstyle - Perl style guide
  3.  
  4. DESCRIPTION
  5.        Each programmer will, of course, have his or her own
  6.        preferences in regards to formatting, but there are some
  7.        general guidelines that will make your programs easier to
  8.        read, understand, and maintain.
  9.  
  10.        The most important thing is to run your programs under the
  11.        -w flag at all times.  You may turn it off explicitly for
  12.        particular portions of code via the $^W variable if you
  13.        must.  You should also always run under use strict or know
  14.        the reason why not.  The <use sigtrap> and even <use
  15.        diagnostics> pragmas may also prove useful.
  16.  
  17.        Regarding aesthetics of code lay out, about the only thing
  18.        Larry cares strongly about is that the closing curly brace
  19.        of a multi-line BLOCK should line up with the keyword that
  20.        started the construct.  Beyond that, he has other
  21.        preferences that aren't so strong:
  22.  
  23.        o   4-column indent.
  24.  
  25.        o   Opening curly on same line as keyword, if possible,
  26.            otherwise line up.
  27.  
  28.        o   Space before the opening curly of a multiline BLOCK.
  29.  
  30.        o   One-line BLOCK may be put on one line, including
  31.            curlies.
  32.  
  33.        o   No space before the semicolon.
  34.  
  35.        o   Semicolon omitted in "short" one-line BLOCK.
  36.  
  37.        o   Space around most operators.
  38.  
  39.        o   Space around a "complex" subscript (inside brackets).
  40.  
  41.        o   Blank lines between chunks that do different things.
  42.  
  43.        o   Uncuddled elses.
  44.  
  45.        o   No space between function name and its opening paren.
  46.  
  47.        o   Space after each comma.
  48.  
  49.        o   Long lines broken after an operator (except "and" and
  50.            "or").
  51.  
  52.        o   Space after last paren matching on current line.
  53.  
  54.        o   Line up corresponding items vertically.
  55.  
  56.        o   Omit redundant punctuation as long as clarity doesn't
  57.            suffer.
  58.  
  59.        Larry has his reasons for each of these things, but he
  60.        doen't claim that everyone else's mind works the same as
  61.        his does.
  62.  
  63.        Here are some other more substantive style issues to think
  64.        about:
  65.  
  66.        o   Just because you CAN do something a particular way
  67.            doesn't mean that you SHOULD do it that way.  Perl is
  68.            designed to give you several ways to do anything, so
  69.            consider picking the most readable one.  For instance
  70.  
  71.                open(FOO,$foo) || die "Can't open $foo: $!";
  72.  
  73.            is better than
  74.  
  75.                die "Can't open $foo: $!" unless open(FOO,$foo);
  76.  
  77.            because the second way hides the main point of the
  78.            statement in a modifier.  On the other hand
  79.  
  80.                print "Starting analysis\n" if $verbose;
  81.  
  82.            is better than
  83.  
  84.                $verbose && print "Starting analysis\n";
  85.  
  86.            since the main point isn't whether the user typed -v
  87.            or not.
  88.  
  89.            Similarly, just because an operator lets you assume
  90.            default arguments doesn't mean that you have to make
  91.            use of the defaults.  The defaults are there for lazy
  92.            systems programmers writing one-shot programs.  If you
  93.            want your program to be readable, consider supplying
  94.            the argument.
  95.  
  96.            Along the same lines, just because you CAN omit
  97.            parentheses in many places doesn't mean that you ought
  98.            to:
  99.  
  100.                return print reverse sort num values %array;
  101.                return print(reverse(sort num (values(%array))));
  102.  
  103.            When in doubt, parenthesize.  At the very least it
  104.            will let some poor schmuck bounce on the % key in vi.
  105.  
  106.            Even if you aren't in doubt, consider the mental
  107.            welfare of the person who has to maintain the code
  108.            after you, and who will probably put parens in the
  109.            wrong place.
  110.  
  111.        o   Don't go through silly contortions to exit a loop at
  112.            the top or the bottom, when Perl provides the last
  113.            operator so you can exit in the middle.  Just
  114.            "outdent" it a little to make it more visible:
  115.  
  116.                LINE:
  117.                    for (;;) {
  118.                        statements;
  119.                      last LINE if $foo;
  120.                        next LINE if /^#/;
  121.                        statements;
  122.                    }
  123.  
  124.        o   Don't be afraid to use loop labels--they're there to
  125.            enhance readability as well as to allow multi-level
  126.            loop breaks.  See the previous example.
  127.  
  128.        o   Avoid using grep() (or map()) or `backticks` in a void
  129.            context, that is, when you just throw away their
  130.            return values.  Those functions all have return
  131.            values, so use them.  Otherwise use a foreach() loop
  132.            or the system() function instead.
  133.  
  134.        o   For portability, when using features that may not be
  135.            implemented on every machine, test the construct in an
  136.            eval to see if it fails.  If you know what version or
  137.            patchlevel a particular feature was implemented, you
  138.            can test $] ($PERL_VERSION in English) to see if it
  139.            will be there.  The Config module will also let you
  140.            interrogate values determined by the Configure program
  141.            when Perl was installed.
  142.  
  143.        o   Choose mnemonic identifiers.  If you can't remember
  144.            what mnemonic means, you've got a problem.
  145.  
  146.        o   While short identifiers like $gotit are probably ok,
  147.            use underscores to separate words.  It is generally
  148.            easier to read $var_names_like_this than
  149.            $VarNamesLikeThis, especially for non-native speakers
  150.            of English. It's also a simple rule that works
  151.            consistently with VAR_NAMES_LIKE_THIS.
  152.  
  153.            Package names are sometimes an exception to this rule.
  154.            Perl informally reserves lowercase module names for
  155.            "pragma" modules like integer and strict.  Other
  156.            modules should begin with a capital letter and use
  157.            mixed case, but probably without underscores due to
  158.            limitations in primitive filesystems' representations
  159.            of module names as files that must fit into a few
  160.            sparse bites.
  161.        o   You may find it helpful to use letter case to indicate
  162.            the scope or nature of a variable. For example:
  163.  
  164.                $ALL_CAPS_HERE   constants only (beware clashes with perl vars!)
  165.                $Some_Caps_Here  package-wide global/static
  166.                $no_caps_here    function scope my() or local() variables
  167.  
  168.            Function and method names seem to work best as all
  169.            lowercase.  E.g., $obj->as_string().
  170.  
  171.            You can use a leading underscore to indicate that a
  172.            variable or function should not be used outside the
  173.            package that defined it.
  174.  
  175.        o   If you have a really hairy regular expression, use the
  176.            /x modifier and put in some whitespace to make it look
  177.            a little less like line noise.  Don't use slash as a
  178.            delimiter when your regexp has slashes or backslashes.
  179.  
  180.        o   Use the new "and" and "or" operators to avoid having
  181.            to parenthesize list operators so much, and to reduce
  182.            the incidence of punctuational operators like && and
  183.            ||.  Call your subroutines as if they were functions
  184.            or list operators to avoid excessive ampersands and
  185.            parens.
  186.  
  187.        o   Use here documents instead of repeated print()
  188.            statements.
  189.  
  190.        o   Line up corresponding things vertically, especially if
  191.            it'd be too long to fit on one line anyway.
  192.  
  193.                $IDX = $ST_MTIME;
  194.                $IDX = $ST_ATIME       if $opt_u;
  195.                $IDX = $ST_CTIME       if $opt_c;
  196.                $IDX = $ST_SIZE        if $opt_s;
  197.  
  198.                mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!";
  199.                chdir($tmpdir)      or die "can't chdir $tmpdir: $!";
  200.                mkdir 'tmp',   0777 or die "can't mkdir $tmpdir/tmp: $!";
  201.  
  202.        o   Always check the return codes of system calls.  Good
  203.            error messages should go to STDERR, include which
  204.            program caused the problem, what the failed system
  205.            call and arguments were, and VERY IMPORTANT) should
  206.            contain the standard system error message for what
  207.            went wrong.  Here's a simple but sufficient example:
  208.  
  209.                opendir(D, $dir)     or die "can't opendir $dir: $!";
  210.  
  211.        o   Line up your translations when it makes sense:
  212.  
  213.                tr [abc]
  214.                   [xyz];
  215.  
  216.        o   Think about reusability.  Why waste brainpower on a
  217.            one-shot when you might want to do something like it
  218.            again?  Consider generalizing your code.  Consider
  219.            writing a module or object class.  Consider making
  220.            your code run cleanly with use strict and -w in
  221.            effect.  Consider giving away your code.  Consider
  222.            changing your whole world view.  Consider... oh, never
  223.            mind.
  224.  
  225.        o   Be consistent.
  226.  
  227.        o   Be nice.
  228.